/* hwInterfaceBase.h */

/************************************************************************************
*                    Copyright Aquantia Corporation
*                              Freeware
*
* Description:
*
*   This file defines the bare minimum required by TCP server from local hwInterface
*
************************************************************************************/

/*! \file
    This file defines the bare minimum required by TCP server from local hwInterface
*/

#ifndef AQ_HW_INTERFACE_BASE_TOKEN
#define AQ_HW_INTERFACE_BASE_TOKEN

#include <tcpServerConfig.h>

/*! \defgroup Local_HW_Interface Local HW Interface
HW Interface functions are required by the TCP server for interfacing the system hardware. The body of these functions needs to be written by the system designer, as the method of interfacing will be unique to the target system. They are designed to be generic read and write access functions.
 @{*/

/* At a bare minimum, the following are required from the local hwInterface: */

/*! This function returns the HW_ErrorFlag.  If set, an error has occurred, and the error message can be read by
    HW_Error() */
unsigned int HW_Fail ();

/*! This function returns the error message. */
char* HW_Error ();

/*! This function performs the initialization of the system to determine the list of devices.  Successful
    initialization returns 1, and failure returns 0 */
unsigned int HW_Initialize ();

/*! This function returns the number of devices in the system */
unsigned int HW_NumberOfDevices ();

/*! This function returns the list of device names in the system */
char** HW_DeviceList ();

/*! This function opens an adapter, where the adapter number references the adapter found in adapter list */
unsigned int HW_OpenAdapter (unsigned int adapter);

/*! This function closes a specific adapter, but does not close the interface */
unsigned int HW_CloseAdapter (unsigned int adapter);

/*! This function closes the interface */
void HW_Close ();

/*! This function performs a write on the specified adapter */
void HW_Write (unsigned int adapter, unsigned int PHY_ID, unsigned int MMD, unsigned int address, unsigned int data);

/*! This function performs a read on the specified adapter */
unsigned int HW_Read (unsigned int adapter, unsigned int PHY_ID, unsigned int MMD, unsigned int address);

/*! Returns the current default adapter number. */
unsigned int HW_GetDefaultAdapter ();

/*! Explicitly designates adapterNumber as the current default adapter.  adapterNumber must be 
 * a valid index into the list of adapters.  The adapter must be open.   A return value of 1  
 * signifies success, 0 failure.  In case of failure, the default adapter will not be changed. */
unsigned int HW_SetDefaultAdapter (unsigned int adapterNumber);

/*! Returns whether buffered read/write operations are supported by the implementation */
unsigned int AQ_API_MDIO_SupportsBlockOperations ();


/* Adding block operation support requires: */

/*! Returns the maximum number of buffered read/write operations supported by the implementation.  Callers 
 * should call HW_BlockOperationExecuteAdapter() before issuing additional calls to HW_BlockWriteAdapter() or 
 * HW_BlockReadAdapter() to avoid a buffer overflow. */
unsigned int AQ_API_MDIO_MaxBlockOperations ();

/*! This function sends a block read to the specified adapter.  These block reads are accumulated until a 
    HW_BlockOperationExecute() call is issued. The maximum number of reads to execute is implementation specific. */
unsigned int HW_BlockReadAdapter (unsigned int adapter, unsigned int PHY_ID, unsigned int MMD, unsigned int address);

/*! This function sends a block write to the specified adapter.  These block writes are accumulated until a 
    HW_BlockOperationExecute() call is issued. The maximum number of writes to execute is implementation specific. */
void HW_BlockWriteAdapter (unsigned int adapter, unsigned int PHY_ID, unsigned int MMD, unsigned int address, unsigned int data);

/*! This function executes the block read on the specified adapter, and returns a pointer to the read results. */
unsigned int* HW_BlockOperationExecuteAdapter (unsigned int adapter, unsigned int PHY_ID);

/*! This function returns the size of the results queue. */
unsigned int HW_BlockReadQueueSize ();


#ifdef BOARD_SUPPORT
  /*! Adding board operation support requires: */
  /*! This function provides board level write access. */
  void Board_WriteAdapter (unsigned int adapter, unsigned int address, unsigned int data);
  
  /*! This function provides board level read access. */
  unsigned int Board_ReadAdapter (unsigned int adapter, unsigned int address);
#endif

/*@}*/

#endif
